Skip to content

Clarify wrap_file lifecycle docs#3461

Closed
ishaanlabs-gg wants to merge 1 commit into
python-trio:mainfrom
ishaanlabs-gg:clarify-wrap-file-lifecycle
Closed

Clarify wrap_file lifecycle docs#3461
ishaanlabs-gg wants to merge 1 commit into
python-trio:mainfrom
ishaanlabs-gg:clarify-wrap-file-lifecycle

Conversation

@ishaanlabs-gg

Copy link
Copy Markdown

Fixes #3379.

This clarifies the asynchronous file object notes for trio.wrap_file():

  • aclose() on the async wrapper closes the wrapped synchronous file object.
  • the async wrapper does not expose a synchronous close() shortcut.
  • Trio does not guarantee that garbage collection of the async wrapper closes the wrapped file.
  • continuing to use the original synchronous file object while also using the async wrapper has the same concurrency caveat as using the async wrapper from multiple tasks.

I also added a 3379.doc.rst newsfragment.

Validation:

  • PATH=/Volumes/STOREJET/2/Dependencies/trio/docs-venv-313/bin:$PATH /Volumes/STOREJET/2/Dependencies/trio/docs-venv-313/bin/sphinx-build -b html -D 'exclude_patterns=._*' source build/html

Notes:

  • The docs environment was installed from docs-requirements.txt into an external SSD venv using Python 3.13.
  • A Python 3.14 docs environment failed while building the pinned immutables==0.21 wheel, before Sphinx ran. Python 3.13 installed the pinned docs requirements cleanly.
  • The exclude_patterns=._* override is only for this local external drive, which creates AppleDouble ._* metadata files that Sphinx otherwise treats as source files.

@A5rocks

A5rocks commented Jun 30, 2026

Copy link
Copy Markdown
Contributor

Sorry but making Claude write docs adds zero value -- people could just ask it. Anyways, tests should be added to make sure we aren't lying in the docs.

@A5rocks A5rocks closed this Jun 30, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

trip.wrap_file() undocumented behavior wrt to sync file object

2 participants